Migrating functionality modules from ProtectServer 2 HSMs to ProtectServer 3 HSMs
It is not possible to use the same functionality modules (FMs) compiled for ProtectServer 2 HSMs on ProtectServer 3 HSMs for the following reasons:
-
The underlying FM libraries are newer.
-
The FM binary signing format has changed.
-
The FM header is different (version 3).
Recompile the FMs from source code, using the PTK 7 FM SDK, before installing them on your new ProtectServer 3 External, ProtectServer 3+ External, or ProtectServer 3 PCIe HSM.
This section summarizes changes and enhancements to the FM SDK and toolchain that must be considered before recompiling FMs using the PTK 7 FM SDK.
FM SDK changes
The following changes have been introduced to the FM SDK:
Changes to required compilation flags
The following changes have been introduced to the flags required for FM compilation:
-
The
fPICcompilation flag, which is included in cfgbuild.mak, is required for FM compilation. For more information about cfgbuild.mak, refer to Contents of the $(FMSDK) directory. -
IS_LITTLE_ENDIAN and IS_BIG_ENDIAN do not need to be defined. IS_BIG_ENDIAN is added by fmconfig.mk. For more information about fmconfig.mk, refer to Contents of the $(FMSDK) directory.
-
To manage the endianness of numbers, use the following helper functions, which are included in the endyn.h header file:
-
(hton | ntoh)_(short | long | longlong) for 16-bit, 32-bit, and 64-bit integers.
-
swap16, swap32, and swap64 to indiscriminately change endianness.
-
isBE, isLE to check endianness.
-
-
The integers.h header file has been deprecated.
-
Use the standard data types provided by stdint.h instead. For example, use uint8_t instead of uint8.
-
Map short_t, uint_t, and ulong_t to uint16_t, uint32_t, and uint32_t, respectively.
-
Windows FM cross-compilation support
FMs can only be cross-compiled on Linux systems. Windows users should cross-compile FMs by using a Linux VM or Windows Subsystem for Linux 2 (WSL 2). Refer to Configuring WSL 2 for FM development and deployment.
Older FMs can only be used with default message timeout settings
If an FM was previously deployed on a ProtectServer 2 HSM and has been recompiled for redeployment on a ProtectServer 3 HSM with ProtectToolkit 7 in Network mode, you must leave the timeout parameter of MD_SendReceive at its default value (600). For more information about MD_SendReceive, refer to MD_SendReceive.
Toolchain changes
The following enhancements have been introduced to the toolchain:
-
Uses GNU Compiler Collection (GCC) version 4.8.2.
-
Includes a C/C++ cross-compiler.
Note
If you use a version of GCC newer than 4.8.2, warnings might appear during FM compilation.
libstdc++ is not included in the HSM firmware, so C++ FMs should not use it. To avoid linking to libstdc++, compile C++ FMs with -fno-rtti -fno-exceptions -nodefaultlibs -lgcc -lc. If compilation errors appear, the code is still dependent on libstdc++.
For more information about FM development, refer to FM SDK programming.
